Date: Tue, 23 May 2006 08:21:15 +0200 From: Alexander Leidinger <Alexander@Leidinger.net> To: gnn@freebsd.org Cc: Poul-Henning Kamp <phk@phk.freebsd.dk>, hellmuth.michaelis@t-online.de, Julian Elischer <julian@elischer.org>, freebsd-arch@freebsd.org Subject: Re: doxygen target (was: Re: cvs commit: src Makefile.inc1 ObsoleteFiles.inc src/etc/defaults rc.conf src/etc/mtree BSD.usr.dist src/etc/rc.d Makefile isdnd pcvt syscons src/release/picobsd/build picobsd src/share/man/man4 Makefile atkbd.4 kbdmux.4 pcvt.4 splash.4 vkbd.4 ...) Message-ID: <20060523082115.v4832wbvhcgccwwk@netchild.homeip.net> In-Reply-To: <m2bqtpk4b0.wl%gnn@neville-neil.com> References: <200605181516.15541.hm@kts.org> <39318.1147960050@critter.freebsd.dk> <m2ejyrl0gd.wl%gnn@neville-neil.com> <20060519143116.9iuvd81es0g0owkc@netchild.homeip.net> <m2fyj3f3re.wl%gnn@neville-neil.com> <20060522101825.adfzv59y1eogwocs@netchild.homeip.net> <m2bqtpk4b0.wl%gnn@neville-neil.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Quoting gnn@freebsd.org (from Mon, 22 May 2006 16:50:11 -0700): > At Mon, 22 May 2006 10:18:25 +0200, > Alexander Leidinger wrote: >> Regarding the make target, do you think about "cd /usr/src; make >> doxygen" or about "cd /usr/src/<mumble>; make doxygen"? > > Yes :-) It hsould be possible to be as specific or non-specific as > possible. There can then be nightly builds of the docs, much like > running global nightly to get cross references like I put up on > codespelunking.org I try to come up with the /usr/src doxygen target first. >> The targets in the .tar.bz2 generate a HTML version too. Currently >> the HTML version is around 300 MB, and it only covers a small part >> of the kernel. Shall the HTML version also be generated (not >> available online)? What about the destination, where do you want the >> HTML version and/or the PDF version (needs pdflatex as a build tool) >> to be placed (I can't come up with a good destination)? The HTML >> version is generated by doxygen directly, the PDF needs to be >> generated from the latex version, so in case of the PDF version it >> would make sense to have a "doxygen" and "doxygeninstall" target, >> but not for the HTML version (except you want to generate everything >> in OBJDIR and then do a copy to the destination). >> >> Yes, I'm asking bikeshed questions... but only because I can't think >> of a good answer myself ATM. > > My preference, and I'm not a Doxygen guru, is that we generate HTML > from /usr/src into a /usr/doc directory, which is like /usr/obj, then Sounds fine to me. One directory per subsystem if we go the split-up way. > some folks can serve /usr/doc on the net. Sub directory builds should > make sub-directory doc directories. I.e. /usr/src/sys/netinet/doc. I > think that /usr/src/sys is already a special root which gets a doc > directory, and I think that's fine. For now I want to emphasize > simplicity. I'm not sure the subdirectory builds are that simple to implement in a =20 generic fashion (I have to play around with some ideas here...). =20 Adding a target by hand to each interesting subdirectory is easy. > THe other thing we need guidance on is, if people want to, how to most > easily add clear annotations to soiurce that make Doxygen happy. A > one page cheat sheet would go a long way towards making this usable by > people who don't like to write documentation :-) I think http://www.stack.nl/~dimitri/doxygen/docblocks.html provides a =20 good start (until someone writes doxygen_style(9) :-) ). A FAQ is available at http://www.stack.nl/~dimitri/doxygen/faq.html =20 and http://www.stack.nl/~dimitri/doxygen/commands.html contains a list =20 of all doxygen recognized documentation-commands. Bye, Alexander. --=20 Selling GoodYear Eagle F1 235/40ZR18, 2x 4mm + 2x 5mm, ~150 EUR you have to pick it up between Germany/Saarland and Luxembourg/Capellen http://www.Leidinger.net Alexander @ Leidinger.net: PGP ID =3D B0063FE7 http://www.FreeBSD.org netchild @ FreeBSD.org : PGP ID =3D 72077137
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060523082115.v4832wbvhcgccwwk>